﻿@page "/docs/components/select"

<DocsPageTitle>
    Select component
</DocsPageTitle>

<DocsPageParagraph>
    Use <Code>Select</Code> to combine many choices into one menu.
</DocsPageParagraph>

<DocsPageSubtitle>
    Structure
</DocsPageSubtitle>

<ul>
    <li>
        <Code Tag>Select</Code>
        <ul>
            <li>
                <Code Tag>SelectItem</Code>
            </li>
            <li>
                <Code Tag>SelectGroup</Code> Optional tag used to group select items
            </li>
        </ul>
    </li>
</ul>

<DocsPageParagraph>
    <Code>Select</Code> and <Code>SelectItem</Code> are generic components and they support all of the basic value
    types line int, string, enum, etc. Nullable types are also supported. Since they are generic component they also
    come with some special rules that must be followed:
</DocsPageParagraph>

<ul>
    <li>
        Value type must be known. When using member variable on <Code>bind-*</Code> or <Code>SelectedValue</Code> attributes, the value type
        will be recognized automatically. Otherwise you must use TValue to define it eg (TValue=”int”).
    </li>
    <li>
        Value type must be the same in both <Code>Select</Code> and <Code>SelectItem</Code>.
    </li>
    <li>
        String values must be defined with special syntax eg. @("@(\"hello\")"), see
        <Blazorise.Link To="https://github.com/dotnet/aspnetcore/issues/7785" Target="Target.Blank">#7785</Blazorise.Link>
    </li>
</ul>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="Basic" />
    <DocsPageSectionContent Outlined FullWidth>
        <BasicSelectExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="BasicSelectExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Multiple">
        Add the <Code>Multiple</Code> attribute to allow more than one option to be selected.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MultipleSelectExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MultipleSelectExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Groups">
        You can also group items into categories for better user experience.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <GroupSelectExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="GroupSelectExample" />
</DocsPageSection>

<DocsPageSubtitle>
    Binding
</DocsPageSubtitle>

<DocsPageParagraph>
    The process is basically the same for the single and for multiple select. The only difference is that
    <Code>SelectedValue</Code> attribute is used for single select mode, and <Code>SelectedValues</Code> attribute
    is used for multi-selection. Keep in mind that <Code>Multiple</Code> must be set to true for multi-selection to work properly.
</DocsPageParagraph>

<Alert Color="Color.Info" Visible>
    <AlertDescription>
        <Strong>Note:</Strong> The <Code>Value</Code> attribute is required on the <Code>SelectItem</Code>. Otherwise the <Code>Select</Code> will not behave as expected.
    </AlertDescription>
</Alert>

<DocsPageSection>
    <DocsPageSectionHeader Title="Two-way binding">
        By using <Code>bind-*</Code> attribute the selected item value will be automatically assigned to the member variable.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <SelectWithBindExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="SelectWithBindExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Manual event binding">
        When using the event <Code>SelectedValueChanged</Code>, you also must define the <Code>SelectedValue</Code> attribute.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <SelectWithEventExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="SelectWithEventExample" />
</DocsPageSection>

<DocsPageSubtitle>
    Attributes
</DocsPageSubtitle>

<DocsAttributes Title="Select">
    <DocsAttributesItem Name="TValue" Type="generic">
        <Code>SelectedValue</Code> or <Code>SelectedValues</Code> data type.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedValue" Type="TValue" Default="default">
        Selected item value when in single edit mode.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedValues" Type="IReadOnlyList<TValue>" Default="default">
        Selected item value when in multi edit mode.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedValueChanged" Type="EventCallback<TValue>">
        Occurs when the selected item value has changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SelectedValuesChanged" Type="EventCallback<IReadOnlyList<TValue>>">
        Occurs when the selected items value has changed (only when <Code>Multiple="true"</Code>).
    </DocsAttributesItem>
    <DocsAttributesItem Name="MaxVisibleItems" Type="int?" Default="null">
        Specifies how many options should be shown at once.
    </DocsAttributesItem>
</DocsAttributes>

<DocsAttributes Title="SelectItem">
    <DocsAttributesItem Name="TValue" Type="generic">
        <Code>Value</Code> data type.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Value" Type="TValue" Default="default">
        Gets or sets the item value.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Disabled" Type="bool" Default="false">
        Disable the item from mouse click.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Hidden" Type="bool" Default="false">
        Hides the item from the list - useful for default.
    </DocsAttributesItem>
</DocsAttributes>

<DocsAttributes Title="SelectGroup">
    <DocsAttributesItem Name="Label" Type="string">
        Gets or sets the group label.
    </DocsAttributesItem>
</DocsAttributes>